home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / Pod / Simple / HTMLBatch.pm < prev    next >
Encoding:
Text File  |  2009-06-26  |  38.2 KB  |  1,343 lines
  1.  
  2. require 5;
  3. package Pod::Simple::HTMLBatch;
  4. use strict;
  5. use vars qw( $VERSION $HTML_RENDER_CLASS $HTML_EXTENSION
  6.  $CSS $JAVASCRIPT $SLEEPY $SEARCH_CLASS @ISA
  7. );
  8. $VERSION = '3.02';
  9. @ISA = ();  # Yup, we're NOT a subclass of Pod::Simple::HTML!
  10.  
  11. # TODO: nocontents stylesheets. Strike some of the color variations?
  12.  
  13. use Pod::Simple::HTML ();
  14. BEGIN {*esc = \&Pod::Simple::HTML::esc }
  15. use File::Spec ();
  16. use UNIVERSAL ();
  17.   # "Isn't the Universe an amazing place?  I wouldn't live anywhere else!"
  18.  
  19. use Pod::Simple::Search;
  20. $SEARCH_CLASS ||= 'Pod::Simple::Search';
  21.  
  22. BEGIN {
  23.   if(defined &DEBUG) { } # no-op
  24.   elsif( defined &Pod::Simple::DEBUG ) { *DEBUG = \&Pod::Simple::DEBUG }
  25.   else { *DEBUG = sub () {0}; }
  26. }
  27.  
  28. $SLEEPY = 1 if !defined $SLEEPY and $^O =~ /mswin|mac/i;
  29. # flag to occasionally sleep for $SLEEPY - 1 seconds.
  30.  
  31. $HTML_RENDER_CLASS ||= "Pod::Simple::HTML";
  32.  
  33. #
  34. # Methods beginning with "_" are particularly internal and possibly ugly.
  35. #
  36.  
  37. Pod::Simple::_accessorize( __PACKAGE__,
  38.  'verbose', # how verbose to be during batch conversion
  39.  'html_render_class', # what class to use to render
  40.  'contents_file', # If set, should be the name of a file (in current directory)
  41.                   # to write the list of all modules to
  42.  'index', # will set $htmlpage->index(...) to this (true or false)
  43.  'progress', # progress object
  44.  'contents_page_start',  'contents_page_end',
  45.  
  46.  'css_flurry', '_css_wad', 'javascript_flurry', '_javascript_wad',
  47.  'no_contents_links', # set to true to suppress automatic adding of << links.
  48.  '_contents',
  49. );
  50.  
  51. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  52. # Just so we can run from the command line more easily
  53. sub go {
  54.   @ARGV == 2 or die sprintf(
  55.     "Usage: perl -M%s -e %s:go indirs outdir\n  (or use \"\@INC\" for indirs)\n",
  56.     __PACKAGE__, __PACKAGE__, 
  57.   );
  58.   
  59.   if(defined($ARGV[1]) and length($ARGV[1])) {
  60.     my $d = $ARGV[1];
  61.     -e $d or die "I see no output directory named \"$d\"\nAborting";
  62.     -d $d or die "But \"$d\" isn't a directory!\nAborting";
  63.     -w $d or die "Directory \"$d\" isn't writeable!\nAborting";
  64.   }
  65.   
  66.   __PACKAGE__->batch_convert(@ARGV);
  67. }
  68. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  69.  
  70.  
  71. sub new {
  72.   my $new = bless {}, ref($_[0]) || $_[0];
  73.   $new->html_render_class($HTML_RENDER_CLASS);
  74.   $new->verbose(1 + DEBUG);
  75.   $new->_contents([]);
  76.   
  77.   $new->index(1);
  78.  
  79.   $new->       _css_wad([]);         $new->css_flurry(1);
  80.   $new->_javascript_wad([]);  $new->javascript_flurry(1);
  81.   
  82.   $new->contents_file(
  83.     'index' . ($HTML_EXTENSION || $Pod::Simple::HTML::HTML_EXTENSION)
  84.   );
  85.   
  86.   $new->contents_page_start( join "\n", grep $_,
  87.     $Pod::Simple::HTML::Doctype_decl,
  88.     "<html><head>",
  89.     "<title>Perl Documentation</title>",
  90.     $Pod::Simple::HTML::Content_decl,
  91.     "</head>",
  92.     "\n<body class='contentspage'>\n<h1>Perl Documentation</h1>\n"
  93.   ); # override if you need a different title
  94.   
  95.   
  96.   $new->contents_page_end( sprintf(
  97.     "\n\n<p class='contentsfooty'>Generated by %s v%s under Perl v%s\n<br >At %s GMT, which is %s local time.</p>\n\n</body></html>\n",
  98.     esc(
  99.       ref($new),
  100.       eval {$new->VERSION} || $VERSION,
  101.       $], scalar(gmtime), scalar(localtime), 
  102.   )));
  103.  
  104.   return $new;
  105. }
  106.  
  107. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  108.  
  109. sub muse {
  110.   my $self = shift;
  111.   if($self->verbose) {
  112.     print 'T+', int(time() - $self->{'_batch_start_time'}), "s: ", @_, "\n";
  113.   }
  114.   return 1;
  115. }
  116.  
  117. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  118.  
  119. sub batch_convert {
  120.   my($self, $dirs, $outdir) = @_;
  121.   $self ||= __PACKAGE__; # tolerate being called as an optionless function
  122.   $self = $self->new unless ref $self; # tolerate being used as a class method
  123.  
  124.   if(!defined($dirs)  or  $dirs eq ''  or  $dirs eq '@INC' ) {
  125.     $dirs = '';
  126.   } elsif(ref $dirs) {
  127.     # OK, it's an explicit set of dirs to scan, specified as an arrayref.
  128.   } else {
  129.     # OK, it's an explicit set of dirs to scan, specified as a
  130.     #  string like "/thing:/also:/whatever/perl" (":"-delim, as usual)
  131.     #  or, under MSWin, like "c:/thing;d:/also;c:/whatever/perl" (";"-delim!)
  132.     require Config;
  133.     my $ps = quotemeta( $Config::Config{'path_sep'} || ":" );
  134.     $dirs = [ grep length($_), split qr/$ps/, $dirs ];
  135.   }
  136.  
  137.   $outdir = $self->filespecsys->curdir
  138.    unless defined $outdir and length $outdir;
  139.  
  140.   $self->_batch_convert_main($dirs, $outdir);
  141. }
  142.  
  143. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  144.  
  145. sub _batch_convert_main {
  146.   my($self, $dirs, $outdir) = @_;
  147.   # $dirs is either false, or an arrayref.    
  148.   # $outdir is a pathspec.
  149.   
  150.   $self->{'_batch_start_time'} ||= time();
  151.  
  152.   $self->muse( "= ", scalar(localtime) );
  153.   $self->muse( "Starting batch conversion to \"$outdir\"" );
  154.  
  155.   my $progress = $self->progress;
  156.   if(!$progress and $self->verbose > 0 and $self->verbose() <= 5) {
  157.     require Pod::Simple::Progress;
  158.     $progress = Pod::Simple::Progress->new(
  159.         ($self->verbose  < 2) ? () # Default omission-delay
  160.       : ($self->verbose == 2) ? 1  # Reduce the omission-delay
  161.                               : 0  # Eliminate the omission-delay
  162.     );
  163.     $self->progress($progress);
  164.   }
  165.   
  166.   if($dirs) {
  167.     $self->muse(scalar(@$dirs), " dirs to scan: @$dirs");
  168.   } else {
  169.     $self->muse("Scanning \@INC.  This could take a minute or two.");
  170.   }
  171.   my $mod2path = $self->find_all_pods($dirs ? $dirs : ());
  172.   $self->muse("Done scanning.");
  173.  
  174.   my $total = keys %$mod2path;
  175.   unless($total) {
  176.     $self->muse("No pod found.  Aborting batch conversion.\n");
  177.     return $self;
  178.   }
  179.  
  180.   $progress and $progress->goal($total);
  181.   $self->muse("Now converting pod files to HTML.",
  182.     ($total > 25) ? "  This will take a while more." : ()
  183.   );
  184.  
  185.   $self->_spray_css(        $outdir );
  186.   $self->_spray_javascript( $outdir );
  187.  
  188.   $self->_do_all_batch_conversions($mod2path, $outdir);
  189.  
  190.   $progress and $progress->done(sprintf (
  191.     "Done converting %d files.",  $self->{"__batch_conv_page_count"}
  192.   ));
  193.   return $self->_batch_convert_finish($outdir);
  194.   return $self;
  195. }
  196.  
  197.  
  198. sub _do_all_batch_conversions {
  199.   my($self, $mod2path, $outdir) = @_;
  200.   $self->{"__batch_conv_page_count"} = 0;
  201.  
  202.   foreach my $module (sort {lc($a) cmp lc($b)} keys %$mod2path) {
  203.     $self->_do_one_batch_conversion($module, $mod2path, $outdir);
  204.     sleep($SLEEPY - 1) if $SLEEPY;
  205.   }
  206.  
  207.   return;
  208. }
  209.  
  210. sub _batch_convert_finish {
  211.   my($self, $outdir) = @_;
  212.   $self->write_contents_file($outdir);
  213.   $self->muse("Done with batch conversion.  $$self{'__batch_conv_page_count'} files done.");
  214.   $self->muse( "= ", scalar(localtime) );
  215.   $self->progress and $self->progress->done("All done!");
  216.   return;
  217. }
  218.  
  219. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  220.  
  221. sub _do_one_batch_conversion {
  222.   my($self, $module, $mod2path, $outdir, $outfile) = @_;
  223.  
  224.   my $retval;
  225.   my $total    = scalar keys %$mod2path;
  226.   my $infile   = $mod2path->{$module};
  227.   my @namelets = grep m/\S/, split "::", $module;
  228.         # this can stick around in the contents LoL
  229.   my $depth    = scalar @namelets;
  230.   die "Contentless thingie?! $module $infile" unless @namelets; #sanity
  231.     
  232.   $outfile  ||= do {
  233.     my @n = @namelets;
  234.     $n[-1] .= $HTML_EXTENSION || $Pod::Simple::HTML::HTML_EXTENSION;
  235.     $self->filespecsys->catfile( $outdir, @n );
  236.   };
  237.  
  238.   my $progress = $self->progress;
  239.  
  240.   my $page = $self->html_render_class->new;
  241.   if(DEBUG > 5) {
  242.     $self->muse($self->{"__batch_conv_page_count"} + 1, "/$total: ",
  243.       ref($page), " render ($depth) $module => $outfile");
  244.   } elsif(DEBUG > 2) {
  245.     $self->muse($self->{"__batch_conv_page_count"} + 1, "/$total: $module => $outfile")
  246.   }
  247.  
  248.   # Give each class a chance to init the converter:
  249.   
  250.   $page->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
  251.    if $page->can('batch_mode_page_object_init');
  252.   $self->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
  253.    if $self->can('batch_mode_page_object_init');
  254.     
  255.   # Now get busy...
  256.   $self->makepath($outdir => \@namelets);
  257.  
  258.   $progress and $progress->reach($self->{"__batch_conv_page_count"}, "Rendering $module");
  259.  
  260.   if( $retval = $page->parse_from_file($infile, $outfile) ) {
  261.     ++ $self->{"__batch_conv_page_count"} ;
  262.     $self->note_for_contents_file( \@namelets, $infile, $outfile );
  263.   } else {
  264.     $self->muse("Odd, parse_from_file(\"$infile\", \"$outfile\") returned false.");
  265.   }
  266.  
  267.   $page->batch_mode_page_object_kill($self, $module, $infile, $outfile, $depth)
  268.    if $page->can('batch_mode_page_object_kill');
  269.   # The following isn't a typo.  Note that it switches $self and $page.
  270.   $self->batch_mode_page_object_kill($page, $module, $infile, $outfile, $depth)
  271.    if $self->can('batch_mode_page_object_kill');
  272.     
  273.   DEBUG > 4 and printf "%s %sb < $infile %s %sb\n",
  274.      $outfile, -s $outfile, $infile, -s $infile
  275.   ;
  276.  
  277.   undef($page);
  278.   return $retval;
  279. }
  280.  
  281. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  282. sub filespecsys { $_[0]{'_filespecsys'} || 'File::Spec' }
  283.  
  284. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  285.  
  286. sub note_for_contents_file {
  287.   my($self, $namelets, $infile, $outfile) = @_;
  288.  
  289.   # I think the infile and outfile parts are never used. -- SMB
  290.   # But it's handy to have them around for debugging.
  291.  
  292.   if( $self->contents_file ) {
  293.     my $c = $self->_contents();
  294.     push @$c,
  295.      [ join("::", @$namelets), $infile, $outfile, $namelets ]
  296.      #            0               1         2         3
  297.     ;
  298.     DEBUG > 3 and print "Noting @$c[-1]\n";
  299.   }
  300.   return;
  301. }
  302.  
  303. #_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
  304.  
  305. sub write_contents_file {
  306.   my($self, $outdir) = @_;
  307.   my $outfile  = $self->_contents_filespec($outdir) || return;
  308.  
  309.   $self->muse("Preparing list of modules for ToC");
  310.  
  311.   my($toplevel,           # maps  toplevelbit => [all submodules]
  312.      $toplevel_form_freq, # ends up being  'foo' => 'Foo'
  313.     ) = $self->_prep_contents_breakdown;
  314.  
  315.   my $Contents = eval { $self->_wopen($outfile) };
  316.   if( $Contents ) {
  317.     $self->muse( "Writing contents file $outfile" );
  318.   } else {
  319.     warn "Couldn't write-open contents file $outfile: $!\nAbort writing to $outfile at all";
  320.     return;
  321.   }
  322.  
  323.   $self->_write_contents_start(  $Contents, $outfile, );
  324.   $self->_write_contents_middle( $Contents, $outfile, $toplevel, $toplevel_form_freq );
  325.   $self->_write_contents_end(    $Contents, $outfile, );
  326.   return $outfile;
  327. }
  328.  
  329. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  330.  
  331. sub _write_contents_start {
  332.   my($self, $Contents, $outfile) = @_;
  333.   my $starter = $self->contents_page_start || '';
  334.   
  335.   {
  336.     my $css_wad = $self->_css_wad_to_markup(1);
  337.     if( $css_wad ) {
  338.       $starter =~ s{(</head>)}{\n$css_wad\n$1}i;  # otherwise nevermind
  339.     }
  340.     
  341.     my $javascript_wad = $self->_javascript_wad_to_markup(1);
  342.     if( $javascript_wad ) {
  343.       $starter =~ s{(</head>)}{\n$javascript_wad\n$1}i;   # otherwise nevermind
  344.     }
  345.   }
  346.  
  347.   unless(print $Contents $starter, "<dl class='superindex'>\n" ) {
  348.     warn "Couldn't print to $outfile: $!\nAbort writing to $outfile at all";
  349.     close($Contents);
  350.     return 0;
  351.   }
  352.   return 1;
  353. }
  354.  
  355. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  356.  
  357. sub _write_contents_middle {
  358.   my($self, $Contents, $outfile, $toplevel2submodules, $toplevel_form_freq) = @_;
  359.  
  360.   foreach my $t (sort keys %$toplevel2submodules) {
  361.     my @downlines = sort {$a->[-1] cmp $b->[-1]}
  362.                           @{ $toplevel2submodules->{$t} };
  363.     
  364.     printf $Contents qq[<dt><a name="%s">%s</a></dt>\n<dd>\n],
  365.       esc( $t, $toplevel_form_freq->{$t} )
  366.     ;
  367.     
  368.     my($path, $name);
  369.     foreach my $e (@downlines) {
  370.       $name = $e->[0];
  371.       $path = join( "/", '.', esc( @{$e->[3]} ) )
  372.         . ($HTML_EXTENSION || $Pod::Simple::HTML::HTML_EXTENSION);
  373.       print $Contents qq{  <a href="$path">}, esc($name), "</a>  \n";
  374.     }
  375.     print $Contents "</dd>\n\n";
  376.   }
  377.   return 1;
  378. }
  379.  
  380. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  381.  
  382. sub _write_contents_end {
  383.   my($self, $Contents, $outfile) = @_;
  384.   unless(
  385.     print $Contents "</dl>\n",
  386.       $self->contents_page_end || '',
  387.   ) {
  388.     warn "Couldn't write to $outfile: $!";
  389.   }
  390.   close($Contents) or warn "Couldn't close $outfile: $!";
  391.   return 1;
  392. }
  393.  
  394. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  395.  
  396. sub _prep_contents_breakdown {
  397.   my($self) = @_;
  398.   my $contents = $self->_contents;
  399.   my %toplevel; # maps  lctoplevelbit => [all submodules]
  400.   my %toplevel_form_freq; # ends up being  'foo' => 'Foo'
  401.                                # (mapping anycase forms to most freq form)
  402.   
  403.   foreach my $entry (@$contents) {
  404.     my $toplevel = 
  405.       $entry->[0] =~ m/^perl\w*$/ ? 'perl_core_docs'
  406.           # group all the perlwhatever docs together
  407.       : $entry->[3][0] # normal case
  408.     ;
  409.     ++$toplevel_form_freq{ lc $toplevel }{ $toplevel };
  410.     push @{ $toplevel{ lc $toplevel } }, $entry;
  411.     push @$entry, lc($entry->[0]); # add a sort-order key to the end
  412.   }
  413.  
  414.   foreach my $toplevel (sort keys %toplevel) {
  415.     my $fgroup = $toplevel_form_freq{$toplevel};
  416.     $toplevel_form_freq{$toplevel} =
  417.     (
  418.       sort { $fgroup->{$b} <=> $fgroup->{$a}  or  $a cmp $b }
  419.         keys %$fgroup
  420.       # This hash is extremely unlikely to have more than 4 members, so this
  421.       # sort isn't so very wasteful
  422.     )[0];
  423.   }
  424.  
  425.   return(\%toplevel, \%toplevel_form_freq) if wantarray;
  426.   return \%toplevel;
  427. }
  428.  
  429. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  430.  
  431. sub _contents_filespec {
  432.   my($self, $outdir) = @_;
  433.   my $outfile = $self->contents_file;
  434.   return unless $outfile;
  435.   return $self->filespecsys->catfile( $outdir, $outfile );
  436. }
  437.  
  438. #_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
  439.  
  440. sub makepath {
  441.   my($self, $outdir, $namelets) = @_;
  442.   return unless @$namelets > 1;
  443.   for my $i (0 .. ($#$namelets - 1)) {
  444.     my $dir = $self->filespecsys->catdir( $outdir, @$namelets[0 .. $i] );
  445.     if(-e $dir) {
  446.       die "$dir exists but not as a directory!?" unless -d $dir;
  447.       next;
  448.     }
  449.     DEBUG > 3 and print "  Making $dir\n";
  450.     mkdir $dir, 0777
  451.      or die "Can't mkdir $dir: $!\nAborting"
  452.     ;
  453.   }
  454.   return;
  455. }
  456.  
  457. #_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
  458.  
  459. sub batch_mode_page_object_init {
  460.   my $self = shift;
  461.   my($page, $module, $infile, $outfile, $depth) = @_;
  462.   
  463.   # TODO: any further options to percolate onto this new object here?
  464.  
  465.   $page->default_title($module);
  466.   $page->index( $self->index );
  467.  
  468.   $page->html_css(        $self->       _css_wad_to_markup($depth) );
  469.   $page->html_javascript( $self->_javascript_wad_to_markup($depth) );
  470.  
  471.   $self->add_header_backlink($page, $module, $infile, $outfile, $depth);
  472.   $self->add_footer_backlink($page, $module, $infile, $outfile, $depth);
  473.  
  474.  
  475.   return $self;
  476. }
  477.  
  478. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  479.  
  480. sub add_header_backlink {
  481.   my $self = shift;
  482.   return if $self->no_contents_links;
  483.   my($page, $module, $infile, $outfile, $depth) = @_;
  484.   $page->html_header_after_title( join '',
  485.     $page->html_header_after_title || '',
  486.  
  487.     qq[<p class="backlinktop"><b><a name="___top" href="],
  488.     $self->url_up_to_contents($depth),
  489.     qq[" accesskey="1" title="All Documents"><<</a></b></p>\n],
  490.   )
  491.    if $self->contents_file
  492.   ;
  493.   return;
  494. }
  495.  
  496. sub add_footer_backlink {
  497.   my $self = shift;
  498.   return if $self->no_contents_links;
  499.   my($page, $module, $infile, $outfile, $depth) = @_;
  500.   $page->html_footer( join '',
  501.     qq[<p class="backlinkbottom"><b><a name="___bottom" href="],
  502.     $self->url_up_to_contents($depth),
  503.     qq[" title="All Documents"><<</a></b></p>\n],
  504.     
  505.     $page->html_footer || '',
  506.   )
  507.    if $self->contents_file
  508.   ;
  509.   return;
  510. }
  511.  
  512. sub url_up_to_contents {
  513.   my($self, $depth) = @_;
  514.   --$depth;
  515.   return join '/', ('..') x $depth, esc($self->contents_file);
  516. }
  517.  
  518. #_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
  519.  
  520. sub find_all_pods {
  521.   my($self, $dirs) = @_;
  522.   # You can override find_all_pods in a subclass if you want to
  523.   #  do extra filtering or whatnot.  But for the moment, we just
  524.   #  pass to modnames2paths:
  525.   return $self->modnames2paths($dirs);
  526. }
  527.  
  528. #_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
  529.  
  530. sub modnames2paths { # return a hashref mapping modulenames => paths
  531.   my($self, $dirs) = @_;
  532.  
  533.   my $m2p;
  534.   {
  535.     my $search = $SEARCH_CLASS->new;
  536.     DEBUG and print "Searching via $search\n";
  537.     $search->verbose(1) if DEBUG > 10;
  538.     $search->progress( $self->progress->copy->goal(0) ) if $self->progress;
  539.     $search->shadows(0);  # don't bother noting shadowed files
  540.     $search->inc(     $dirs ? 0      :  1 );
  541.     $search->survey(  $dirs ? @$dirs : () );
  542.     $m2p = $search->name2path;
  543.     die "What, no name2path?!" unless $m2p;
  544.   }
  545.  
  546.   $self->muse("That's odd... no modules found!") unless keys %$m2p;
  547.   if( DEBUG > 4 ) {
  548.     print "Modules found (name => path):\n";
  549.     foreach my $m (sort {lc($a) cmp lc($b)} keys %$m2p) {
  550.       print "  $m  $$m2p{$m}\n";
  551.     }
  552.     print "(total ",     scalar(keys %$m2p), ")\n\n";
  553.   } elsif( DEBUG ) {
  554.     print      "Found ", scalar(keys %$m2p), " modules.\n";
  555.   }
  556.   $self->muse( "Found ", scalar(keys %$m2p), " modules." );
  557.   
  558.   # return the Foo::Bar => /whatever/Foo/Bar.pod|pm hashref
  559.   return $m2p;
  560. }
  561.  
  562. #===========================================================================
  563.  
  564. sub _wopen {
  565.   # this is abstracted out so that the daemon class can override it
  566.   my($self, $outpath) = @_;
  567.   require Symbol;
  568.   my $out_fh = Symbol::gensym();
  569.   DEBUG > 5 and print "Write-opening to $outpath\n";
  570.   return $out_fh if open($out_fh, "> $outpath");
  571.   require Carp;  
  572.   Carp::croak("Can't write-open $outpath: $!");
  573. }
  574.  
  575. #==========================================================================
  576.  
  577. sub add_css {
  578.   my($self, $url, $is_default, $name, $content_type, $media, $_code) = @_;
  579.   return unless $url;
  580.   unless($name) {
  581.     # cook up a reasonable name based on the URL
  582.     $name = $url;
  583.     if( $name !~ m/\?/ and $name =~ m{([^/]+)$}s ) {
  584.       $name = $1;
  585.       $name =~ s/\.css//i;
  586.     }
  587.   }
  588.   $media        ||= 'all';
  589.   $content_type ||= 'text/css';
  590.   
  591.   my $bunch = [$url, $name, $content_type, $media, $_code];
  592.   if($is_default) { unshift @{ $self->_css_wad }, $bunch }
  593.   else            { push    @{ $self->_css_wad }, $bunch }
  594.   return;
  595. }
  596.  
  597. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  598.  
  599. sub _spray_css {
  600.   my($self, $outdir) = @_;
  601.  
  602.   return unless $self->css_flurry();
  603.   $self->_gen_css_wad();
  604.  
  605.   my $lol = $self->_css_wad;
  606.   foreach my $chunk (@$lol) {
  607.     my $url = $chunk->[0];
  608.     my $outfile;
  609.     if( ref($chunk->[-1]) and $url =~ m{^(_[-a-z0-9_]+\.css$)} ) {
  610.       $outfile = $self->filespecsys->catfile( $outdir, $1 );
  611.       DEBUG > 5 and print "Noting $$chunk[0] as a file I'll create.\n";
  612.     } else {
  613.       DEBUG > 5 and print "OK, noting $$chunk[0] as an external CSS.\n";
  614.       # Requires no further attention.
  615.       next;
  616.     }
  617.     
  618.     #$self->muse( "Writing autogenerated CSS file $outfile" );
  619.     my $Cssout = $self->_wopen($outfile);
  620.     print $Cssout ${$chunk->[-1]}
  621.      or warn "Couldn't print to $outfile: $!\nAbort writing to $outfile at all";
  622.     close($Cssout);
  623.     DEBUG > 5 and print "Wrote $outfile\n";
  624.   }
  625.  
  626.   return;
  627. }
  628.  
  629. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  630.  
  631. sub _css_wad_to_markup {
  632.   my($self, $depth) = @_;
  633.   
  634.   my @css  = @{ $self->_css_wad || return '' };
  635.   return '' unless @css;
  636.   
  637.   my $rel = 'stylesheet';
  638.   my $out = '';
  639.  
  640.   --$depth;
  641.   my $uplink = $depth ? ('../' x $depth) : '';
  642.  
  643.   foreach my $chunk (@css) {
  644.     next unless $chunk and @$chunk;
  645.  
  646.     my( $url1, $url2, $title, $type, $media) = (
  647.       $self->_maybe_uplink( $chunk->[0], $uplink ),
  648.       esc(grep !ref($_), @$chunk)
  649.     );
  650.  
  651.     $out .= qq{<link rel="$rel" title="$title" type="$type" href="$url1$url2" media="$media" >\n};
  652.  
  653.     $rel = 'alternate stylesheet'; # alternates = all non-first iterations
  654.   }
  655.   return $out;
  656. }
  657.  
  658. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  659. sub _maybe_uplink {
  660.   # if the given URL looks relative, return the given uplink string --
  661.   # otherwise return emptystring
  662.   my($self, $url, $uplink) = @_;
  663.   ($url =~ m{^\./} or $url !~ m{[/\:]} )
  664.     ? $uplink
  665.     : ''
  666.     # qualify it, if/as needed
  667. }
  668.  
  669. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  670. sub _gen_css_wad {
  671.   my $self = $_[0];
  672.   my $css_template = $self->_css_template;
  673.   foreach my $variation (
  674.  
  675.    # Commented out for sake of concision:
  676.    #
  677.    #  011n=black_with_red_on_white
  678.    #  001n=black_with_yellow_on_white
  679.    #  101n=black_with_green_on_white
  680.    #  110=white_with_yellow_on_black
  681.    #  010=white_with_green_on_black
  682.    #  011=white_with_blue_on_black
  683.    #  100=white_with_red_on_black
  684.   
  685.    qw[
  686.     110n=black_with_blue_on_white
  687.     010n=black_with_magenta_on_white
  688.     100n=black_with_cyan_on_white
  689.  
  690.     101=white_with_purple_on_black
  691.     001=white_with_navy_blue_on_black
  692.  
  693.     010a=grey_with_green_on_black
  694.     010b=white_with_green_on_grey
  695.     101an=black_with_green_on_grey
  696.     101bn=grey_with_green_on_white
  697.   ]) {
  698.  
  699.     my $outname = $variation;
  700.     my($flipmode, @swap) = ( ($4 || ''), $1,$2,$3)
  701.       if $outname =~ s/^([012])([012])([[012])([a-z]*)=?//s;
  702.     @swap = () if '010' eq join '', @swap; # 010 is a swop-no-op!
  703.   
  704.     my $this_css =
  705.       "/* This file is autogenerated.  Do not edit.  $variation */\n\n"
  706.       . $css_template;
  707.  
  708.     # Only look at three-digitty colors, for now at least.
  709.     if( $flipmode =~ m/n/ ) {
  710.       $this_css =~ s/(#[0-9a-fA-F]{3})\b/_color_negate($1)/eg;
  711.       $this_css =~ s/\bthin\b/medium/g;
  712.     }
  713.     $this_css =~ s<#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])\b>
  714.                   < join '', '#', ($1,$2,$3)[@swap] >eg   if @swap;
  715.  
  716.     if(   $flipmode =~ m/a/)
  717.        { $this_css =~ s/#fff\b/#999/gi } # black -> dark grey
  718.     elsif($flipmode =~ m/b/)
  719.        { $this_css =~ s/#000\b/#666/gi } # white -> light grey
  720.  
  721.     my $name = $outname;    
  722.     $name =~ tr/-_/  /;
  723.     $self->add_css( "_$outname.css", 0, $name, 0, 0, \$this_css);
  724.   }
  725.  
  726.   # Now a few indexless variations:
  727.   foreach my $variation (qw[
  728.     black_with_blue_on_white  white_with_purple_on_black
  729.     white_with_green_on_grey  grey_with_green_on_white
  730.   ]) {
  731.     my $outname = "indexless_$variation";
  732.     my $this_css = join "\n",
  733.       "/* This file is autogenerated.  Do not edit.  $outname */\n",
  734.       "\@import url(\"./_$variation.css\");",
  735.       ".indexgroup { display: none; }",
  736.       "\n",
  737.     ;
  738.     my $name = $outname;    
  739.     $name =~ tr/-_/  /;
  740.     $self->add_css( "_$outname.css", 0, $name, 0, 0, \$this_css);
  741.   }
  742.  
  743.   return;
  744. }
  745.  
  746. sub _color_negate {
  747.   my $x = lc $_[0];
  748.   $x =~ tr[0123456789abcdef]
  749.           [fedcba9876543210];
  750.   return $x;
  751. }
  752.  
  753. #===========================================================================
  754.  
  755. sub add_javascript {
  756.   my($self, $url, $content_type, $_code) = @_;
  757.   return unless $url;
  758.   push  @{ $self->_javascript_wad }, [
  759.     $url, $content_type || 'text/javascript', $_code
  760.   ];
  761.   return;
  762. }
  763.  
  764. sub _spray_javascript {
  765.   my($self, $outdir) = @_;
  766.   return unless $self->javascript_flurry();
  767.   $self->_gen_javascript_wad();
  768.  
  769.   my $lol = $self->_javascript_wad;
  770.   foreach my $script (@$lol) {
  771.     my $url = $script->[0];
  772.     my $outfile;
  773.     
  774.     if( ref($script->[-1]) and $url =~ m{^(_[-a-z0-9_]+\.js$)} ) {
  775.       $outfile = $self->filespecsys->catfile( $outdir, $1 );
  776.       DEBUG > 5 and print "Noting $$script[0] as a file I'll create.\n";
  777.     } else {
  778.       DEBUG > 5 and print "OK, noting $$script[0] as an external JavaScript.\n";
  779.       next;
  780.     }
  781.     
  782.     #$self->muse( "Writing JavaScript file $outfile" );
  783.     my $Jsout = $self->_wopen($outfile);
  784.  
  785.     print $Jsout ${$script->[-1]}
  786.      or warn "Couldn't print to $outfile: $!\nAbort writing to $outfile at all";
  787.     close($Jsout);
  788.     DEBUG > 5 and print "Wrote $outfile\n";
  789.   }
  790.  
  791.   return;
  792. }
  793.  
  794. sub _gen_javascript_wad {
  795.   my $self = $_[0];
  796.   my $js_code = $self->_javascript || return;
  797.   $self->add_javascript( "_podly.js", 0, \$js_code);
  798.   return;
  799. }
  800.  
  801. sub _javascript_wad_to_markup {
  802.   my($self, $depth) = @_;
  803.   
  804.   my @scripts  = @{ $self->_javascript_wad || return '' };
  805.   return '' unless @scripts;
  806.   
  807.   my $out = '';
  808.  
  809.   --$depth;
  810.   my $uplink = $depth ? ('../' x $depth) : '';
  811.  
  812.   foreach my $s (@scripts) {
  813.     next unless $s and @$s;
  814.  
  815.     my( $url1, $url2, $type, $media) = (
  816.       $self->_maybe_uplink( $s->[0], $uplink ),
  817.       esc(grep !ref($_), @$s)
  818.     );
  819.  
  820.     $out .= qq{<script type="$type" src="$url1$url2"></script>\n};
  821.   }
  822.   return $out;
  823. }
  824.  
  825. #===========================================================================
  826.  
  827. sub _css_template { return $CSS }
  828. sub _javascript   { return $JAVASCRIPT }
  829.  
  830. $CSS = <<'EOCSS';
  831. /* For accessibility reasons, never specify text sizes in px/pt/pc/in/cm/mm */
  832.  
  833. @media all { .hide { display: none; } }
  834.  
  835. @media print {
  836.   .noprint, div.indexgroup, .backlinktop, .backlinkbottom { display: none }
  837.  
  838.   * {
  839.     border-color: black !important;
  840.     color: black !important;
  841.     background-color: transparent !important;
  842.     background-image: none !important;
  843.   }
  844.  
  845.   dl.superindex > dd  {
  846.     word-spacing: .6em;
  847.   }
  848. }
  849.  
  850. @media aural, braille, embossed {
  851.   div.indexgroup  { display: none; }  /* Too noisy, don't you think? */
  852.   dl.superindex > dt:before { content: "Group ";  }
  853.   dl.superindex > dt:after  { content: " contains:"; }
  854.   .backlinktop    a:before  { content: "Back to contents"; }
  855.   .backlinkbottom a:before  { content: "Back to contents"; }
  856. }
  857.  
  858. @media aural {
  859.   dl.superindex > dt  { pause-before: 600ms; }
  860. }
  861.  
  862. @media screen, tty, tv, projection {
  863.   .noscreen { display: none; }
  864.  
  865.   a:link    { color: #7070ff; text-decoration: underline; }
  866.   a:visited { color: #e030ff; text-decoration: underline; }
  867.   a:active  { color: #800000; text-decoration: underline; }
  868.   body.contentspage a            { text-decoration: none; }
  869.   a.u { color: #fff !important; text-decoration: none; }
  870.  
  871.   body.pod {
  872.     margin: 0 5px;
  873.     color:            #fff;
  874.     background-color: #000;
  875.   }
  876.  
  877.   body.pod h1, body.pod h2, body.pod h3, body.pod h4  {
  878.     font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif;
  879.     font-weight: normal;
  880.     margin-top: 1.2em;
  881.     margin-bottom: .1em;
  882.     border-top: thin solid transparent;
  883.     /* margin-left: -5px;  border-left: 2px #7070ff solid;  padding-left: 3px; */
  884.   }
  885.   
  886.   body.pod h1  { border-top-color: #0a0; }
  887.   body.pod h2  { border-top-color: #080; }
  888.   body.pod h3  { border-top-color: #040; }
  889.   body.pod h4  { border-top-color: #010; }
  890.  
  891.   p.backlinktop + h1 { border-top: none; margin-top: 0em;  }
  892.   p.backlinktop + h2 { border-top: none; margin-top: 0em;  }
  893.   p.backlinktop + h3 { border-top: none; margin-top: 0em;  }
  894.   p.backlinktop + h4 { border-top: none; margin-top: 0em;  }
  895.  
  896.   body.pod dt {
  897.     font-size: 105%; /* just a wee bit more than normal */
  898.   }
  899.  
  900.   .indexgroup { font-size: 80%; }
  901.  
  902.   .backlinktop,   .backlinkbottom    {
  903.     margin-left:  -5px;
  904.     margin-right: -5px;
  905.     background-color:         #040;
  906.     border-top:    thin solid #050;
  907.     border-bottom: thin solid #050;
  908.   }
  909.   
  910.   .backlinktop a, .backlinkbottom a  {
  911.     text-decoration: none;
  912.     color: #080;
  913.     background-color:  #000;
  914.     border: thin solid #0d0;
  915.   }
  916.   .backlinkbottom { margin-bottom: 0; padding-bottom: 0; }
  917.   .backlinktop    { margin-top:    0; padding-top:    0; }
  918.  
  919.   body.contentspage {
  920.     color:            #fff;
  921.     background-color: #000;
  922.   }
  923.   
  924.   body.contentspage h1  {
  925.     color:            #0d0;
  926.     margin-left: 1em;
  927.     margin-right: 1em;
  928.     text-indent: -.9em;
  929.     font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif;
  930.     font-weight: normal;
  931.     border-top:    thin solid #fff;
  932.     border-bottom: thin solid #fff;
  933.     text-align: center;
  934.   }
  935.  
  936.   dl.superindex > dt  {
  937.     font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif;
  938.     font-weight: normal;
  939.     font-size: 90%;
  940.     margin-top: .45em;
  941.     /* margin-bottom: -.15em; */
  942.   }
  943.   dl.superindex > dd  {
  944.     word-spacing: .6em;    /* most important rule here! */
  945.   }
  946.   dl.superindex > a:link  {
  947.     text-decoration: none;
  948.     color: #fff;
  949.   }
  950.  
  951.   .contentsfooty {
  952.     border-top: thin solid #999;
  953.     font-size: 90%;
  954.   }
  955.   
  956. }
  957.  
  958. /* The End */
  959.  
  960. EOCSS
  961.  
  962. #==========================================================================
  963.  
  964. $JAVASCRIPT = <<'EOJAVASCRIPT';
  965.  
  966. // From http://www.alistapart.com/articles/alternate/
  967.  
  968. function setActiveStyleSheet(title) {
  969.   var i, a, main;
  970.   for(i=0  ;  (a = document.getElementsByTagName("link")[i])  ;  i++) {
  971.     if(a.getAttribute("rel").indexOf("style") != -1 && a.getAttribute("title")) {
  972.       a.disabled = true;
  973.       if(a.getAttribute("title") == title) a.disabled = false;
  974.     }
  975.   }
  976. }
  977.  
  978. function getActiveStyleSheet() {
  979.   var i, a;
  980.   for(i=0  ;  (a = document.getElementsByTagName("link")[i])  ;  i++) {
  981.     if(   a.getAttribute("rel").indexOf("style") != -1
  982.        && a.getAttribute("title")
  983.        && !a.disabled
  984.        ) return a.getAttribute("title");
  985.   }
  986.   return null;
  987. }
  988.  
  989. function getPreferredStyleSheet() {
  990.   var i, a;
  991.   for(i=0  ;  (a = document.getElementsByTagName("link")[i])  ;  i++) {
  992.     if(   a.getAttribute("rel").indexOf("style") != -1
  993.        && a.getAttribute("rel").indexOf("alt") == -1
  994.        && a.getAttribute("title")
  995.        ) return a.getAttribute("title");
  996.   }
  997.   return null;
  998. }
  999.  
  1000. function createCookie(name,value,days) {
  1001.   if (days) {
  1002.     var date = new Date();
  1003.     date.setTime(date.getTime()+(days*24*60*60*1000));
  1004.     var expires = "; expires="+date.toGMTString();
  1005.   }
  1006.   else expires = "";
  1007.   document.cookie = name+"="+value+expires+"; path=/";
  1008. }
  1009.  
  1010. function readCookie(name) {
  1011.   var nameEQ = name + "=";
  1012.   var ca = document.cookie.split(';');
  1013.   for(var i=0  ;  i < ca.length  ;  i++) {
  1014.     var c = ca[i];
  1015.     while (c.charAt(0)==' ') c = c.substring(1,c.length);
  1016.     if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length,c.length);
  1017.   }
  1018.   return null;
  1019. }
  1020.  
  1021. window.onload = function(e) {
  1022.   var cookie = readCookie("style");
  1023.   var title = cookie ? cookie : getPreferredStyleSheet();
  1024.   setActiveStyleSheet(title);
  1025. }
  1026.  
  1027. window.onunload = function(e) {
  1028.   var title = getActiveStyleSheet();
  1029.   createCookie("style", title, 365);
  1030. }
  1031.  
  1032. var cookie = readCookie("style");
  1033. var title = cookie ? cookie : getPreferredStyleSheet();
  1034. setActiveStyleSheet(title);
  1035.  
  1036. // The End
  1037.  
  1038. EOJAVASCRIPT
  1039.  
  1040. # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  1041. 1;
  1042. __END__
  1043.  
  1044.  
  1045. =head1 NAME
  1046.  
  1047. Pod::Simple::HTMLBatch - convert several Pod files to several HTML files
  1048.  
  1049. =head1 SYNOPSIS
  1050.  
  1051.   perl -MPod::Simple::HTMLBatch -e 'Pod::Simple::HTMLBatch::go' in out
  1052.  
  1053.  
  1054. =head1 DESCRIPTION
  1055.  
  1056. This module is used for running batch-conversions of a lot of HTML
  1057. documents 
  1058.  
  1059. This class is NOT a subclass of Pod::Simple::HTML
  1060. (nor of bad old Pod::Html) -- although it uses
  1061. Pod::Simple::HTML for doing the conversion of each document.
  1062.  
  1063. The normal use of this class is like so:
  1064.  
  1065.   use Pod::Simple::HTMLBatch;
  1066.   my $batchconv = Pod::Simple::HTMLBatch->new;
  1067.   $batchconv->some_option( some_value );
  1068.   $batchconv->some_other_option( some_other_value );
  1069.   $batchconv->batch_convert( \@search_dirs, $output_dir );
  1070.  
  1071. =head2 FROM THE COMMAND LINE
  1072.  
  1073. Note that this class also provides
  1074. (but does not export) the function Pod::Simple::HTMLBatch::go.
  1075. This is basically just a shortcut for C<<
  1076. Pod::Simple::HTMLBatch->batch_convert(@ARGV) >>.
  1077. It's meant to be handy for calling from the command line.
  1078.  
  1079. However, the shortcut requires that you specify exactly two command-line
  1080. arguments, C<indirs> and C<outdir>.
  1081.  
  1082. Example:
  1083.  
  1084.   % mkdir out_html
  1085.   % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html
  1086.       (to convert the pod from Perl's @INC
  1087.        files under the directory ../htmlversion)
  1088.  
  1089. (Note that the command line there contains a literal atsign-I-N-C.  This
  1090. is handled as a special case by batch_convert, in order to save you having
  1091. to enter the odd-looking "" as the first command-line parameter when you
  1092. mean "just use whatever's in @INC".)
  1093.  
  1094. Example:
  1095.  
  1096.   % mkdir ../seekrut
  1097.   % chmod og-rx ../seekrut
  1098.   % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go . ../htmlversion
  1099.       (to convert the pod under the current dir into HTML
  1100.        files under the directory ../htmlversion)
  1101.  
  1102. Example:
  1103.  
  1104.   % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go happydocs .
  1105.       (to convert all pod from happydocs into the current directory)
  1106.  
  1107.  
  1108.  
  1109. =head1 MAIN METHODS
  1110.  
  1111. =over
  1112.  
  1113. =item $batchconv = Pod::Simple::HTMLBatch->new;
  1114.  
  1115. This TODO
  1116.  
  1117.  
  1118. =item $batchconv->batch_convert( I<indirs>, I<outdir> );
  1119.  
  1120. this TODO
  1121.  
  1122. =item $batchconv->batch_convert( undef    , ...);
  1123.  
  1124. =item $batchconv->batch_convert( q{@INC}, ...);
  1125.  
  1126. These two values for I<indirs> specify that the normal Perl @INC
  1127.  
  1128. =item $batchconv->batch_convert( \@dirs , ...);
  1129.  
  1130. This specifies that the input directories are the items in
  1131. the arrayref C<\@dirs>.
  1132.  
  1133. =item $batchconv->batch_convert( "somedir" , ...);
  1134.  
  1135. This specifies that the director "somedir" is the input.
  1136. (This can be an absolute or relative path, it doesn't matter.)
  1137.  
  1138. A common value you might want would be just "." for the current
  1139. directory:
  1140.  
  1141.      $batchconv->batch_convert( "." , ...);
  1142.  
  1143.  
  1144. =item $batchconv->batch_convert( 'somedir:someother:also' , ...);
  1145.  
  1146. This specifies that you want the dirs "somedir", "somother", and "also"
  1147. scanned, just as if you'd passed the arrayref
  1148. C<[qw( somedir someother also)]>.  Note that a ":"-separator is normal
  1149. under Unix, but Under MSWin, you'll need C<'somedir;someother;also'>
  1150. instead, since the pathsep on MSWin is ";" instead of ":".  (And
  1151. I<that> is because ":" often comes up in paths, like
  1152. C<"c:/perl/lib">.)
  1153.  
  1154. (Exactly what separator character should be used, is gotten from
  1155. C<$Config::Config{'path_sep'}>, via the L<Config> module.)
  1156.  
  1157. =item $batchconv->batch_convert( ... , undef );
  1158.  
  1159. This specifies that you want the HTML output to go into the current
  1160. directory.
  1161.  
  1162. (Note that a missing or undefined value means a different thing in
  1163. the first slot than in the second.  That's so that C<batch_convert()>
  1164. with no arguments (or undef arguments) means "go from @INC, into
  1165. the current directory.)
  1166.  
  1167. =item $batchconv->batch_convert( ... , 'somedir' );
  1168.  
  1169. This specifies that you want the HTML output to go into the
  1170. directory 'somedir'.
  1171. (This can be an absolute or relative path, it doesn't matter.)
  1172.  
  1173. =back
  1174.  
  1175.  
  1176. Note that you can also call C<batch_convert> as a class method,
  1177. like so:
  1178.  
  1179.   Pod::Simple::HTMLBatch->batch_convert( ... );
  1180.  
  1181. That is just short for this:
  1182.  
  1183.   Pod::Simple::HTMLBatch-> new-> batch_convert(...);
  1184.  
  1185. That is, it runs a conversion with default options, for
  1186. whatever inputdirs and output dir you specify.
  1187.  
  1188.  
  1189. =head2 ACCESSOR METHODS
  1190.  
  1191. The following are all accessor methods -- that is, they don't do anything
  1192. on their own, but just alter the contents of the conversion object,
  1193. which comprises the options for this particular batch conversion.
  1194.  
  1195. We show the "put" form of the accessors below (i.e., the syntax you use
  1196. for setting the accessor to a specific value).  But you can also
  1197. call each method with no parameters to get its current value.  For
  1198. example, C<< $self->contents_file() >> returns the current value of
  1199. the contents_file attribute.
  1200.  
  1201. =over
  1202.  
  1203.  
  1204. =item $batchconv->verbose( I<nonnegative_integer> );
  1205.  
  1206. This controls how verbose to be during batch conversion, as far as
  1207. notes to STDOUT (or whatever is C<select>'d) about how the conversion
  1208. is going.  If 0, no progress information is printed.
  1209. If 1 (the default value), some progress information is printed.
  1210. Higher values print more information.
  1211.  
  1212.  
  1213. =item $batchconv->index( I<true-or-false> );
  1214.  
  1215. This controls whether or not each HTML page is liable to have a little
  1216. table of contents at the top (which we call an "index" for historical
  1217. reasons).  This is true by default.
  1218.  
  1219.  
  1220. =item $batchconv->contents_file( I<filename> );
  1221.  
  1222. If set, should be the name of a file (in the output directory)
  1223. to write the HTML index to.  The default value is "index.html".
  1224. If you set this to a false value, no contents file will be written.
  1225.  
  1226. =item $batchconv->contents_page_start( I<HTML_string> );
  1227.  
  1228. This specifies what string should be put at the beginning of
  1229. the contents page.
  1230. The default is a string more or less like this:
  1231.   
  1232.   <html>
  1233.   <head><title>Perl Documentation</title></head>
  1234.   <body class='contentspage'>
  1235.   <h1>Perl Documentation</h1>
  1236.  
  1237. =item $batchconv->contents_page_end( I<HTML_string> );
  1238.  
  1239. This specifies what string should be put at the end of the contents page.
  1240. The default is a string more or less like this:
  1241.  
  1242.   <p class='contentsfooty'>Generated by
  1243.   Pod::Simple::HTMLBatch v3.01 under Perl v5.008
  1244.   <br >At Fri May 14 22:26:42 2004 GMT,
  1245.   which is Fri May 14 14:26:42 2004 local time.</p>
  1246.  
  1247.  
  1248.  
  1249. =item $batchconv->add_css( $url );
  1250.  
  1251. TODO
  1252.  
  1253. =item $batchconv->add_javascript( $url );
  1254.  
  1255. TODO
  1256.  
  1257. =item $batchconv->css_flurry( I<true-or-false> );
  1258.  
  1259. If true (the default value), we autogenerate some CSS files in the
  1260. output directory, and set our HTML files to use those.
  1261. TODO: continue
  1262.  
  1263. =item $batchconv->javascript_flurry( I<true-or-false> );
  1264.  
  1265. If true (the default value), we autogenerate a JavaScript in the
  1266. output directory, and set our HTML files to use it.  Currently,
  1267. the JavaScript is used only to get the browser to remember what
  1268. stylesheet it prefers.
  1269. TODO: continue
  1270.  
  1271. =item $batchconv->no_contents_links( I<true-or-false> );
  1272.  
  1273. TODO
  1274.  
  1275. =item $batchconv->html_render_class( I<classname> );
  1276.  
  1277. This sets what class is used for rendering the files.
  1278. The default is "Pod::Simple::Search".  If you set it to something else,
  1279. it should probably be a subclass of Pod::Simple::Search, and you should
  1280. C<require> or C<use> that class so that's it's loaded before
  1281. Pod::Simple::HTMLBatch tries loading it.
  1282.  
  1283. =back
  1284.  
  1285.  
  1286.  
  1287.  
  1288. =head1 NOTES ON CUSTOMIZATION
  1289.  
  1290. TODO
  1291.  
  1292.   call add_css($someurl) to add stylesheet as alternate
  1293.   call add_css($someurl,1) to add as primary stylesheet
  1294.  
  1295.   call add_javascript
  1296.  
  1297.   subclass Pod::Simple::HTML and set $batchconv->html_render_class to
  1298.     that classname
  1299.   and maybe override
  1300.     $page->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
  1301.   or maybe override
  1302.     $batchconv->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
  1303.  
  1304.  
  1305.  
  1306. =head1 ASK ME!
  1307.  
  1308. If you want to do some kind of big pod-to-HTML version with some
  1309. particular kind of option that you don't see how to achieve using this
  1310. module, email me (C<sburke@cpan.org>) and I'll probably have a good idea
  1311. how to do it. For reasons of concision and energetic laziness, some
  1312. methods and options in this module (and the dozen modules it depends on)
  1313. are undocumented; but one of those undocumented bits might be just what
  1314. you're looking for.
  1315.  
  1316.  
  1317. =head1 SEE ALSO
  1318.  
  1319. L<Pod::Simple>, L<Pod::Simple::HTMLBatch>, L<perlpod>, L<perlpodspec>
  1320.  
  1321.  
  1322.  
  1323.  
  1324. =head1 COPYRIGHT AND DISCLAIMERS
  1325.  
  1326. Copyright (c) 2004 Sean M. Burke.  All rights reserved.
  1327.  
  1328. This library is free software; you can redistribute it and/or modify it
  1329. under the same terms as Perl itself.
  1330.  
  1331. This program is distributed in the hope that it will be useful, but
  1332. without any warranty; without even the implied warranty of
  1333. merchantability or fitness for a particular purpose.
  1334.  
  1335. =head1 AUTHOR
  1336.  
  1337. Sean M. Burke C<sburke@cpan.org>
  1338.  
  1339. =cut
  1340.  
  1341.  
  1342.  
  1343.